---
title: Setup
slug: project-setup.html
---


import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


The Kotest test framework is supported on JVM, Javascript, Native and Wasm.
To enable Kotest for multiple platforms, follow the steps for the platform you are targeting as detailed in the following tabs.

:::caution
The KMP support in Kotest 6.0 has changed from the previous versions. There is no longer a compiler plugin but a simplified setup.
Please see the rest of this page for details on how to configure Kotest for KMP in Kotest 6.0 and later.
:::

:::tip
When running the Gradle test task, Gradle will cache the output and report no tests executed if no source code has changed.
See the section on rerunning tests for details on how to disable this behaviour.
:::

<Tabs
defaultValue="JVM"
values={[
{label: 'JVM', value: 'JVM'},
{label: 'Kotlin/JS', value: 'JS'},
{label: 'Kotlin/WasmJS', value: 'WasmJS'},
{label: 'Kotlin/Native', value: 'Native'},
{label: 'Android', value: 'Android'},
{label: 'Multiplatform', value: 'Multiplatform'},
]}>
<TabItem value="JVM">

:::tip
A working project with JVM support can be found here:
https://github.com/kotest/kotest-examples
:::

Kotest on the JVM has two ways for running tests. One uses the [Kotest gradle plugin](https://plugins.gradle.org/plugin/io.kotest), which provides detailed test output in the console, and a rich experience in Intellij (in conjuction with the Intellij Kotest plugin).
The other option uses the [JUnit Platform](https://junit.org/junit5/docs/current/user-guide/#running-tests-build-gradle) gradle plugin which is ubiquitous in the JVM ecosystem but lacks some features of the Kotest gradle plugin.

To use the Kotest gradle plugin, add the following to your `build.gradle.kts` file:

```kotlin
plugins {
   id("io.kotest") version "<kotest-version>"
}
```

Add the following dependency to your build:

```kotlin
dependencies {
   testImplementation("io.kotest:kotest-framework-engine:<kotest-version>")
}
```

And then execute the `jvmKotest` task in gradle, or run tests directly from the IDE.

To use the JUnit Platform plugin, add the following to your `build.gradle.kts` file:

```kotlin
tasks.withType<Test>().configureEach {
   useJUnitPlatform()
}
```

Add the following dependency to your build:

```kotlin
dependencies {
   testImplementation("io.kotest:kotest-runner-junit5:<kotest-version>")
}
```

And then execute the `test` task in gradle, or run tests directly from the IDE.

   </TabItem>
   <TabItem value="JS">

:::tip
A working JS project can be found here: https://github.com/kotest/kotest-examples
:::

Add the [Kotest gradle plugin](https://plugins.gradle.org/plugin/io.kotest) and Google KSP plugin to to your build.

For example:

```kotlin
plugins {
   id("io.kotest") version "<kotest-version>"
   id("com.google.devtools.ksp") version "<kotlin-verson>-<ksp-version>"
}
```

Add the `kotest-framework-engine` dependency to your `commonTest` or `jsTest` source set:

```kotlin
kotlin {
   js()
   sourceSets {
      commonTest {
         dependencies {
            implementation("io.kotest:kotest-framework-engine:<kotest-version>")
         }
      }
   }
}
```

Tests can be placed in either `commonTest` or `jsTest`.
Run your tests using the `jsTest` gradle task.

:::note
The JS test engine is feature limited when compared to the JVM test engine. The major restriction is that annotation
based configuration will not work as Kotlin does not expose annotations at runtime to JS code.
:::

   </TabItem>
   <TabItem value="WasmJS">

:::tip
A working WasmJS project can be found here: https://github.com/kotest/kotest-examples
:::

Add the [Kotest gradle plugin](https://plugins.gradle.org/plugin/io.kotest) and Google KSP plugin to to your build.

For example:

```kotlin
plugins {
   id("io.kotest") version "<kotest-version>"
   id("com.google.devtools.ksp") version "<kotlin-verson>-<ksp-version>"
}
```

Add the `kotest-framework-engine` dependency to your `commonTest` or `wasmJsTest` source set:

```kotlin
kotlin {
   wasmJs()
   sourceSets {
      commonTest {
         dependencies {
            implementation("io.kotest:kotest-framework-engine:<kotest-version>")
         }
      }
   }
}
```

Tests can be placed in either `commonTest` or `wasmJsTest`.
Run your tests using the `wasmJsTest` gradle task.

:::note
The WasmJS test engine is feature limited when compared to the JVM test engine. The major restriction is that annotation
based configuration will not work as Kotlin does not expose annotations at runtime to Wasm code.
:::

   </TabItem>
   <TabItem value="Native">

:::tip
A working native project with linux, windows and macos configured, with unit and data driven test examples, can be found here:
https://github.com/kotest/kotest-examples
:::

Add the [Kotest gradle plugin](https://plugins.gradle.org/plugin/io.kotest) and Google KSP plugin to to your build.

For example:

```kotlin
plugins {
   id("io.kotest") version "<kotest-version>"
   id("com.google.devtools.ksp") version "<kotlin-verson>-<ksp-version>"
}
```

Add the `kotest-framework-engine` dependency to your `commonTest`, `nativeTest` or platform specific sourceset:

```kotlin
kotlin {
   linuxX64() // add any supported native target
   sourceSets {
      commonTest {
         dependencies {
            implementation("io.kotest:kotest-framework-engine:<kotest-version>")
         }
      }
   }
}
```

Tests can be placed in either `commonTest` or a specific native sourceset.
      Run your tests using the standard test tasks, for example `linuxX86Test`.

:::note
The native test engine is feature limited when compared to the JVM test engine. The major restriction is that annotation
based configuration will not work as Kotlin does not expose annotations at runtime to native code.
:::

   </TabItem>
   <TabItem value="Android">

:::info
Currently, only Unit tests are supported in Kotest.
The following steps enable Kotest to be used for unit tests - where the Android framework is not needed or is mocked - and that usually reside in the
`src/test` folder of your module.
:::

Kotest on Android uses the [JUnit Platform](https://junit.org/junit5/docs/current/user-guide/#running-tests-build-gradle) gradle plugin.
This requires configuring the android test options block in your build file and then adding the Kotest junit5 runner dependency.

```kotlin
android.testOptions {
   unitTests.all {
      it.useJUnitPlatform()
   }
}
```

```kotlin
dependencies {
   testImplementation 'io.kotest:kotest-runner-junit5:version'
}
```

:::tip
A working Android project with unit and data driven test examples, can be found here:
https://github.com/kotest/kotest-examples
:::


   </TabItem>
   <TabItem value="Multiplatform">

:::tip
A working multiplatform project with JVM, JS and native targets, and unit and data driven test examples, can be found here:
https://github.com/kotest/kotest-examples
:::

Add the [Kotest gradle plugin](https://plugins.gradle.org/plugin/io.kotest) and Google KSP plugin to to your build.

For example:

```kotlin
plugins {
   id("io.kotest") version "<kotest-version>"
   id("com.google.devtools.ksp") version "<kotlin-verson>-<ksp-version>"
}
```

Add the `kotest-framework-engine` dependency to your `commonTest` source set:

```kotlin
kotlin {
   sourceSets {
      commonTest {
         dependencies {
            implementation("io.kotest:kotest-framework-engine:<kotest-version>")
         }
      }
   }
}
```

Tests can be placed in either `commonTest` or a platform specific directory such as `jsTest` or `macosX64Test` etc.
Run your tests using the gradle `check` task, or a platform specific test task such as `macosX64Test`

:::note
The JS, Wasm and native test engines are feature limited when compared to the JVM test engine. The major restriction is that annotation
based configuration will not work as Kotlin does not expose annotations at runtime to non-JVM platforms.
:::

   </TabItem>
</Tabs>


## Re-running tests

By default, Gradle's incremental build will skip running tests if no source code has changed, marking the task as UP-TO-DATE. This can be inconvenient during debugging.

To force your tests to run every time, you can temporarily add the following configuration to your build.gradle.kts file:

```kotlin
tasks.withType<Test>().configureEach {
   logger.lifecycle("UP-TO-DATE check for $name is disabled, forcing it to run.")
   outputs.upToDateWhen { false }
}
```

Quick Alternative: For a single re-run without modifying build files, you can use the --rerun flag from the command line:

```
./gradlew test --rerun
```
